~ chicken-core (chicken-5) /manual/Module (chicken process)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken process)56This module offers procedures for interacting with subprocesses.78* New in CHICKEN 5.4.0: Errors caused by underlying C calls that9 change errno will produce a condition object with an {{errno}}10 property, which can be accessed with11 {{(get-condition-property <the-condition-object> 'exn 'errno)}}.1213=== Processes1415==== process-execute1617<procedure>(process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-ALIST]])</procedure>1819Replaces the running process with a new process image from the program20stored at {{PATHNAME}}, using the C library function {{execvp(3)}}.21If the optional argument {{ARGUMENT-LIST}} is given, then it should22contain a list of strings which are passed as arguments to the subprocess.23If the optional argument {{ENVIRONMENT-ALIST}} is supplied, then the library24function {{execve(2)}} is used, and the environment passed in25{{ENVIRONMENT-ALIST}} (which should be of the form {{(("<NAME>" . "<VALUE>") ...)}})26is given to the invoked process. Note that {{execvp(3)}} respects the27current setting of the {{PATH}} environment variable while {{execve(3)}} does not.2829This procedure never returns; it either replaces the process with a new one30or it raises an exception in case something went wrong executing the program.3132On Windows, these procedures all have an additional optional parameter33{{EXACT-FLAG}}, which defaults to {{#f}}. When {{#f}} is passed, any34argument string with embedded whitespace will be wrapped in35quotes. When {{#t}} no such wrapping occurs.363738==== process-fork3940<procedure>(process-fork [THUNK [KILLOTHERS?]])</procedure>4142Creates a new child process with the UNIX system call43{{fork()}}. Returns either the PID of the child process or 0. If44{{THUNK}} is given, then the child process calls it as a procedure45with no arguments and terminates. If {{THUNK}} is given and the46optional argument {{KILLOTHERS?}} is true, then kill all other47existing threads in the child process, leaving only the current thread48to run {{THUNK}} and terminate.4950'''NOTE''': On native Windows builds (all except cygwin), this51procedure is unimplemented and will raise an error.5253==== process-run5455<procedure>(process-run COMMANDLINE)</procedure><br>56<procedure>(process-run COMMAND ARGUMENT-LIST)</procedure>5758Creates a new child process. The PID of the new process is returned.5960* The single parameter version passes the {{COMMANDLINE}} to the61system shell, so usual argument expansion can take place. Be careful62to properly quote arguments with the {{qs}} procedure to avoid shell63injection vulnerabilities.64* The multiple parameter version directly invokes the {{COMMAND}} with65the {{ARGUMENT-LIST}}, and is vastly preferred over the66single-parameter version because of its better safety.6768==== process-signal6970<procedure>(process-signal PID [SIGNAL])</procedure>7172Sends {{SIGNAL}} to the process with the id {{PID}} using the73UNIX system call {{kill()}}. {{SIGNAL}} defaults to the value74of the variable {{signal/term}}.7576'''NOTE''': On native Windows builds (all except cygwin), this77procedure is unimplemented and will raise an error.7879==== process-spawn8081<procedure>(process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])</procedure>8283Creates and runs a new process with the given {{COMMAND}} filename and84the optional {{ARGUMENT-LIST}} and {{ENVIRONMENT-LIST}}. {{MODE}}85specifies how exactly the process should be executed and must be one86or more of the {{spawn/...}} flags listed below.8788The {{EXACT-FLAG}}, default {{#f}}, controls quote-wrapping of89argument strings. When {{#t}} quote-wrapping is not performed.9091Returns:92* the exit status when synchronous93* the PID when asynchronous94* -1 when failure9596'''NOTE''': On all Unix-like builds (all except native MingW-based97Windows platforms), this procedure is unimplemented and will raise an98error.99100<constant>spawn/overlay</constant>101<constant>spawn/wait</constant>102<constant>spawn/nowait</constant>103<constant>spawn/nowaito</constant>104<constant>spawn/detach</constant>105106These variables contains special flags that specify the exact107semantics of {{process-spawn}}:108109* {{spawn/overlay}} replaces the current process with the new one.110* {{spawn/wait}} suspends execution of the current process until the spawned process returns.111* {{spawn/nowait}} does the opposite ({{spawn/nowaito}} is identical, according to the Microsoft documentation) and runs the process asynchronously.112* {{spawn/detach}} runs the new process in the background, without being attached to a console.113114115==== process-wait116117<procedure>(process-wait [PID [NOHANG]])</procedure>118119Suspends the current process until the child process with120the id {{PID}} has terminated using the UNIX system call121{{waitpid()}}. If {{PID}} is not given, then this procedure122waits for any child process. If {{NOHANG}} is given and not123{{#f}} then the current process is not suspended. This procedure124returns three values:125126* {{PID}} or 0, if {{NOHANG}} is true and the child process has not terminated yet.127* {{#t}} if the process exited normally or {{#f}} otherwise.128* either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.129130Note that suspending the current process implies that all threads131are suspended as well.132133On Windows, {{process-wait}} always returns {{#t}} for a terminated134process and only the exit status is available. (Windows does not135provide signals as an interprocess communication method.)136137138==== process-sleep139140<procedure>(process-sleep SECONDS)</procedure>141142Puts the process to sleep for {{SECONDS}}. Returns either 0 if143the time has completely elapsed, or the number of remaining seconds,144if a signal occurred.145146147==== process148149<procedure>(process COMMANDLINE)</procedure><br>150<procedure>(process COMMAND ARGUMENT-LIST [ENVIRONMENT-ALIST])</procedure>151152Creates a subprocess and returns three values: an input port from153which data written by the sub-process can be read, an output port from154which any data written to will be received as input in the sub-process155and the process-id of the started sub-process. Blocking reads and writes156to or from the ports returned by {{process}} only block the current157thread, not other threads executing concurrently.158159Standard error for the subprocess is linked up to the current160process's standard error (see {{process*}} if you want to reify161its standard error into a separate port).162163* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that164is invoked as a subprocess.165* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}166is directly passed, as is {{ENVIRONMENT-ALIST}}. These arguments have the same form as the ones of {{process-execute}}.167168Not using the shell may be preferrable for security reasons.169170Once both the input- and output ports are closed, an implicit171{{waitpid(3)}} is done to wait for the subprocess to finish or to reap172a subprocess that has terminated. If the subprocess has not finished,173waiting for it will necessarily block all executing threads.174175==== process*176177<procedure>(process* COMMANDLINE)</procedure><br>178<procedure>(process* COMMAND ARGUMENT-LIST [ENVIRONMENT-ALIST])</procedure>179180Like {{process}} but returns 4 values: an input port from181which data written by the sub-process can be read, an output port from182which any data written to will be received as input in the sub-process,183the process-id of the started sub-process, and an input port from184which data written by the sub-process to {{stderr}} can be read.185186=== Shell commands187188The commands below are all string-based. This means you have to be189very careful to properly quote any arguments to subprocesses, to avoid190shell injection bugs which can lead to arbitrary code execution.191192You can quote arguments with the {{qs}} procedure, but it is strongly193recommended you use {{fork}} with {{process-execute}} or the194multi-argument versions of the {{process}}, {{process*}} or195{{process-run}} procedures.196197==== qs198199<procedure>(qs STRING [PLATFORM])</procedure>200201Escapes {{STRING}} suitably for passing to a shell command on {{PLATFORM}}.202{{PLATFORM}} defaults to the value of {{(build-platform)}} and indicates in203which style the argument should be quoted. On Windows systems, the string204is simply enclosed in double-quote ({{"}}) characters, on UNIXish systems,205characters that would have a special meaning to the shell are escaped206using backslash ({{\}}).207208209==== system210211<procedure>(system STRING)</procedure>212213Execute shell command. The functionality offered by this procedure214depends on the capabilities of the host shell. If the forking of a subprocess215failed, an exception is raised. Otherwise the return status of the216subprocess is returned unaltered.217218219On a UNIX system, that value is the raw return value of waitpid(2), which contains signal, core dump and exit status. It is 0 on success. To pull out the signal number or exit status portably requires POSIX calls, but in a pinch you can use something like this:220221<enscript highlight='scheme'>222;; Returns two values: #t if the process exited normally or #f otherwise;223;; and either the exit status, or the signal number if terminated via signal.224(define (process-status rc)225 (define (wait-signaled? x) (not (= 0 (bitwise-and x 127))))226 (define (wait-signal x) (bitwise-and x 127))227 (define (wait-exit-status x) (arithmetic-shift x -8))228 (if (wait-signaled? rc)229 (values #f (wait-signal rc))230 (values #t (wait-exit-status rc))))231232#;> (process-status (system "exit 42"))233#t23442235</enscript>236237==== system*238239<procedure>(system* STRING)</procedure>240241Similar to {{(system STRING)}}, but signals an error should the invoked242program return a nonzero exit status.243244=== Pipes245246==== call-with-input-pipe247==== call-with-output-pipe248249<procedure>(call-with-input-pipe CMDLINE PROC [MODE])</procedure><br>250<procedure>(call-with-output-pipe CMDLINE PROC [MODE])</procedure>251252Call {{PROC}} with a single argument: a input- or output port253for a pipe connected to the subprocess named in {{CMDLINE}}. If254{{PROC}} returns normally, the pipe is closed and any result values255are returned.256257==== close-input-pipe258==== close-output-pipe259260<procedure>(close-input-pipe PORT)</procedure><br>261<procedure>(close-output-pipe PORT)</procedure>262263Closes the pipe given in {{PORT}} and waits until the connected264subprocess finishes. The exit-status code of the invoked process265is returned.266267==== create-pipe268269<procedure>(create-pipe)</procedure>270271The fundamental pipe-creation operator. Calls the C function272{{pipe()}} and returns 2 values: the file-descriptors of the input-273and output-ends of the pipe.274275On Windows, there is an optional parameter {{MODE}}, which defaults276to {{open/binary | open/noinherit}}. This can be {{open/binary}} or277{{open/text}}, optionally or'ed with {{open/noinherit}}.278279280==== open-input-pipe281282<procedure>(open-input-pipe CMDLINE [MODE])</procedure>283284Spawns a subprocess with the command-line string {{CMDLINE}} and285returns a port, from which the output of the process can be read. If286{{MODE}} is specified, it should be the keyword {{#:text}}287(the default) or {{#:binary}}.288289==== open-output-pipe290291<procedure>(open-output-pipe CMDLINE [MODE])</procedure>292293Spawns a subprocess with the command-line string {{CMDLINE}} and294returns a port. Anything written to that port is treated as the input295for the process. If {{MODE}} is specified, it should be the keyword296{{#:text}} (the default) or {{#:binary}}.297298==== pipe/buf299300<constant>pipe/buf</constant>301302This variable contains the maximal number of bytes that can be written303atomically into a pipe or FIFO.304305==== with-input-from-pipe306==== with-output-to-pipe307308<procedure>(with-input-from-pipe CMDLINE THUNK [MODE])</procedure><br>309<procedure>(with-output-to-pipe CMDLINE THUNK [MODE])</procedure>310311Temporarily set the value of312{{current-input-port/current-output-port}} to a port for a313pipe connected to the subprocess named in {{CMDLINE}} and call314the procedure {{THUNK}} with no arguments. After {{THUNK}}315returns normally the pipe is closed and the standard input-/output port316is restored to its previous value and any result values are returned.317318<enscript highlight=scheme>319(with-output-to-pipe320 "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"321 (lambda ()322 (print #<<EOF323 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>324 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8325 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A326 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A327 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d328 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d329 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M330 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J331 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage332 EOF333 ) ) )334</enscript>335336=== Windows specific notes337338Use of UTF8 encoded strings for pathnames is not supported. Windows339uses a 16-bit UNICODE encoding with special system calls for340wide-character support. Only single-byte string encoding can be used.341342---343Previous: [[Module (chicken pretty-print)]]344345Next: [[Module (chicken process signal)]]